﻿<?xml version="1.0" encoding="utf-8" ?>
<comments>
  <!-- 
    Beware that recursive includes will result in duplicate comments if the path used also matches the value after it's been replaced.
    For example, instead of recurisvely matching an XPath such as //para in this file, use an explicit path such as /comments/para so that 
    when the compiler replaces an include within a para tag, the expression /comments/para won't match it.
  -->
  
  <!-- ******************** Shared text ******************** -->

  <!-- Example: <include file='comments.xml' path='//text[@id="some-id"]/child::node()'/> -->

  <text id="PersistenceMode.Session-Reccomendation">
    If possible, it is recommended to set <see cref="AutoInputProtection.PersistenceMode">PersistenceMode</see> to 
    <see cref="AutoInputProtectionPersistenceMode.Session">Session</see> for increased security, although you will have to enable sessions, preferably with a 
    reasonable timeout configured, and you will have to add <see cref="AutoInputProtectionSessionRequestHandler">AutoInputProtectionSessionRequestHandler</see> 
    to the configuration file in place of the typical request handler.
  </text>
  
  <!-- ******************** Shared paragraphs ******************** -->

  <!-- Example: <include file='comments.xml' path='//para[@id="some-id"]'/> -->

  <para id="PersistenceMode_Session_Timeouts">
    The values of the <see cref="AutoInputProtectionControl"/>'s <see cref="AutoInputProtectionControl.ValidationKeepAlive">ValidationKeepAlive</see>,
    <see cref="AutoInputProtectionControl.RequestKeepAlive">RequestKeepAlive</see>,
    <see cref="AutoInputProtectionControl.ValidationTimeout">ValidationTimeout</see> and
    <see cref="AutoInputProtectionControl.RequestTimeout">RequestTimeout</see> properties are ignored when
    <see cref="AutoInputProtectionPersistenceMode.Session"/> is specified.  Instead, the timeouts are controlled implicitly by the session timeout.
  </para>
  <para id="ASPNET_New_SessionID">
    If session state is not being used by the application then ASP.NET will generate a new session ID each time.  If <see cref="AutoInputProtection.UserMode"/> 
    is set to <see cref="AutoInputProtectionUserMode.SessionOrClient"/>, and session state is enabled but <em>PersistenceMode</em> is not set to
    <see cref="AutoInputProtectionPersistenceMode.Session"/>, then it's possible that the session ID will be different on each request.  This will
    effectively prevent user validation from functioning properly.  To fix the problem either store bogus session data so that ASP.NET generates and
    maintains a unique session ID for the lifetime of the session, or use <see cref="AutoInputProtectionSessionRequestHandler"/> instead of
    <see cref="AutoInputProtectionRequestHandler"/> in the configuration file, which will cause ASP.NET to preserve a user's session ID.
  </para>
  <para id="UserMode_Benefits">
    The beneifit of identifying a user is that they may only request one test at a time.  Subsequent requests
    will replace the challenge text stored on the server with a new challenge.  This reduces memory usage and
    ensures that a user cannot accumilate unverified tests that a malicious client can later use to gain
    unauthorized access to protected resources.
  </para>
  <para id="DefaultTextProvider_Rules">
    If the <em>defaultTextProvider</em> attribute is not explicitly set in the configuration file then
    the first provider specified in the <em>textProviders</em> collection element is used as the default and if no providers are specified then a new instance
    of <see cref="BasicEnglishAutoInputProtectionTextProvider"/> is used as the default text provider, with some basic colors and fonts specified.
    It is also used as the default text provider when the <em>textProviders</em> collection element is omitted.
  </para>
  <para id="DefaultImageProvider_Rules">
    If the <em>defaultImageProvider</em> attribute is not explicitly set in the configuration file then
    the first provider specified in the <em>imageProviders</em> collection element is used as the default and if no providers are specified then a new instance
    of <see cref="LineNoiseAutoInputProtectionImageProvider"/> is used as the default image provider.
    It is also used as the default image provider when the <em>imageProviders</em> collection element is omitted.
  </para>
  
  <!-- ******************** Notes ******************** -->

  <!-- Example: <include file='comments.xml' path='//note[@id="some-id"]'/> -->
  
  <note id="ValidationKeepAlive">
    <para>
      Setting <see cref="AutoInputProtectionControl.ValidationKeepAlive">AutoInputProtectionControl.ValidationKeepAlive</see> to <see langword="true"/> is not recommended since it may 
      cause the challenge text that is generated for each request to be persisted on the server indefinitely, increasing memory usage with each request, but 
      only if a validation attempt is never made by the client after the initial request for the challenge.
    </para>
    <para>
      If <see langword="true"/> is used, however, then do not set <see cref="AutoInputProtection.UserMode">AutoInputProtection.UserMode</see> to 
      <see cref="AutoInputProtectionUserMode.None">None</see> if <see cref="AutoInputProtection.PersistenceMode">AutoInputProtection.PersistenceMode</see> is set to 
      <see cref="AutoInputProtectionPersistenceMode.Cache">Cache</see> or else challenge text may be persisted on the server indefinitely.  A value other than 
      <see cref="AutoInputProtectionUserMode.None">None</see> will cause the same behavior, although each user will only be able to persist a single challenge at a time, 
      reducing the chances of a denial of service (DoS) attack that could bring down the server.
    </para>
    <para>
      However, setting <see cref="AutoInputProtection.PersistenceMode">AutoInputProtection.PersistenceMode</see> to <see cref="AutoInputProtectionPersistenceMode.Session">Session</see>, 
      if the session is configured to use a reasonable timeout, will alleviate this problem entirely.  The values of <see cref="AutoInputProtection.UserMode">AutoInputProtection.UserMode</see> 
      and <see cref="AutoInputProtectionControl.ValidationKeepAlive">AutoInputProtectionControl.ValidationKeepAlive</see> will then be inconsequential.
    </para>
  </note>
  
</comments>